home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Users Group Library 1996 July / C-C++ Users Group Library July 1996.iso / vol_300 / 314_01 / mnpc.doc < prev    next >
Text File  |  1990-05-14  |  17KB  |  483 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.      
  8.      
  9.      
  10.      
  11.      
  12.                          The Microcom MNP Library
  13.                           (Microsoft C Version)
  14.      
  15.      
  16.      
  17.                            PROGRAMMER'S MANUAL
  18.      
  19.      
  20.      
  21.      
  22.      
  23.      
  24.      
  25.      
  26.      
  27.      
  28.      
  29.      
  30.      
  31.      
  32.                                 Version 1.0
  33.      
  34.                              December 15, 1987
  35.      
  36.      
  37.      
  38.      
  39.      
  40.      
  41.      
  42.      
  43.      
  44.      
  45.      
  46.      
  47.      
  48.      
  49.      
  50.      
  51.      
  52.      
  53.      
  54.      
  55.      
  56.      
  57.      
  58.                               Microcom, Inc.
  59.                           1400 Providence Highway
  60.                             Norwood, MA 02062
  61.  
  62.  
  63.  
  64.  
  65.  
  66.      
  67.      
  68.      The Microcom MNP Library and MNP are trademarks of Microcom, Inc.
  69.      Microsoft and MS-DOS are trademarks of Microsoft Corporation.  
  70.      IBM is a registered trademark of International Business Machines.
  71.      
  72.      
  73.      This manual is not subject to copyright and may be freely copied.
  74.      
  75.      
  76.      
  77.      
  78.      
  79.      
  80.      
  81.      
  82.      
  83.      
  84.      
  85.      
  86.      
  87.      
  88.      
  89.      
  90.      
  91.      
  92.      
  93.      
  94.      
  95.      
  96.      
  97.      
  98.      
  99.      
  100.      
  101.      
  102.      
  103.      
  104.      
  105.      
  106.      
  107.      
  108.      
  109.      
  110.      Questions relating to the Microcom MNP Library should be directed to
  111.      Microcom at:
  112.      
  113.                               Microcom, Inc.
  114.                        15303 Ventura Blvd., Suite 900
  115.                           Sherman Oaks, CA 91403
  116.                   Voice: (818)986-4212  Fax: (818)986-4214
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.      
  124.      1. INTRODUCTION
  125.      
  126.           The Microcom MNP Library is a set of subroutines which implement the
  127.      stream mode of the link protocol in Microcom Networking Protocol (MNP).
  128.      This mode of the MNP link protocol is appropriate for interworking with MNP
  129.      error-correcting modems or with other software implementations which use
  130.      the Microcom MNP Library or other compatible software.
  131.      
  132.           This version of the library provides a set of C and assembly
  133.      language routines which are designed to be easily integrated into an
  134.      application program written in C and compiled using the Microsoft C
  135.      compiler (version 4.0).  Through the use of these routines, an
  136.      application is able to perform error-free data communications over a
  137.      physical-connection, such as one established on the public switched
  138.      telephone network.
  139.      
  140.           These MNP Library subroutines are especially for the IBM Personal
  141.      Computer family (and compatibles) under PCDOS (MS-DOS).  Hardware
  142.      facilities for asynchronous communications are required.
  143.  
  144.  
  145.  
  146.  
  147.  
  148.      2. LIBRARY MODULES
  149.      
  150.           The Microcom MNP LIbrary is supplied in one of two forms, object
  151.      library only and object library with source.  The source version is de-
  152.      scribed in more detail in a file ('readme.doc') supplied as part of the
  153.      source version distribution.
  154.      
  155.           In the case of the object library only form, the distribution diskette
  156.      contains one file, mnp.lib, which includes the various object modules
  157.      which make up the MNP Library.
  158.      
  159.           When building the executable form of a particular application, the
  160.      mnp.lib file should be specified if the application calls any MNP sub-
  161.      routine described in this document.  The manner in which library modules
  162.      are specified for inclusion varies according to the linkage editor
  163.      employed in building the application program run module.
  164.  
  165.  
  166.  
  167.  
  168.  
  169.      3. LINK MANAGEMENT
  170.      
  171.           In general, the MNP link follows the life of the normal physical-
  172.      connection.  Immediately after the physical-connection is made (e.g. after
  173.      a modem first reports carrier detected), the application must attempt the
  174.      establishment of the Link via the MNPCONNECT subroutine.  MNP-capable
  175.      modems which answer the incoming telephone call, for example, must receive
  176.      the Link establishment sequence within 4 seconds of physical-connection
  177.      establishment.  If a link is not attempted within this period, such modems
  178.      may fall back to a normal connection and it will not be possible to provide
  179.      a reliable connection on that particular call.
  180.      
  181.           Link termination, performed via the MNPDISCONNECT call, should
  182.      immediately precede termination of the physical-connection, i.e. right
  183.      before hanging up the telephone.  Note that the Link is active for the
  184.      entire duration of the physical-connection.
  185.      
  186.           During the data phase of the Link (i.e. after establishment but before
  187.      termination), the Link must be kept running by allowing the Link code to
  188.      execute periodically.  Any of the data phase calls, namely MNPSEND,
  189.      MNPRECEIVE, MNPSTATUS, and MNPBREAK, will accomplish this.  One of these
  190.      routines must be called every 250ms or so which means that the Link code
  191.      gets a chance to run about 4 times per second.  The absolute interval is
  192.      not critical and it may be possible to reduce the frequency as well and
  193.      still get reasonable performance.  Polling the Link code, however, must
  194.      occur with a predictable frequency otherwise the Link may be lost.  When
  195.      the Link is lost, an MNP error-correcting modem may clear the call.
  196.      
  197.           When a Link is in progress, all line I/O is performed via the
  198.      appropriate MNP call rather than by using other C mechanisms.  It 
  199.      may be the case, however, that the com port opened elsewhere in the
  200.      application, must remain open.
  201.      
  202.           Data sent and received on the Link will be "chunked" depending on the
  203.      number of bytes which happen to be sent in a single data message.  The
  204.      maximum amount in a single message is 64 bytes.  This "chunking" is not
  205.      noticeable to the sender but can be perceived by the data receiver.
  206.      Strings of data may be split over more than one data message and some
  207.      messages may have to be sent more than once when there is noise on the
  208.      connection.  Retransmission can be seen by the application as an
  209.      interruption, possibly in the middle of some data string.  The application
  210.      should be examined to see if there are any cases involving timing
  211.      dependencies which could be adversely effected by this kind of 
  212.      irregularity in the data flow.
  213.  
  214.  
  215.  
  216.  
  217.  
  218.      4. LINK INTERFACE SUBROUTINES
  219.      
  220.      4.1  Link Establishment - MNPCONNECT
  221.      
  222.           MNPCONNECT is used to establish a Link.  It is called after the
  223.      physical-connection has been established.  It can take up to 5 seconds
  224.      for an MNPCONNECT call to complete.
  225.      
  226.           MNPCONNECT has the following parameters:
  227.      
  228.                RATE - an integer which indicates the speed of the
  229.                       physical-connection, as follows:
  230.      
  231.                           1 = 110 bps
  232.                           2 = 300 bps
  233.                           4 = 1200 bps
  234.                           5 = 2400 bps
  235.      
  236.                       [Note: Other speeds are not supported in this
  237.                        version of the Microcom MNP Library.]
  238.      
  239.                FORMAT - an integer which indicates the data format,
  240.                         as follows:
  241.      
  242.                          0 = 8 data bits, no parity
  243.                          1 = 7 data bits, even parity
  244.                          2 = 7 data bits, odd parity
  245.                          3 = 7 data bits, mark parity
  246.                          4 = 7 data bits, space parity
  247.      
  248.                       [Note: In this Library version, once the Link
  249.                        is established, it is not possible to change
  250.                        format.]
  251.      
  252.                PORT -  an integer which indicates the communications
  253.                        port, as follows:
  254.      
  255.                          1 = COM1
  256.                          2 = COM2
  257.      
  258.                       [Note: This Library version does not support
  259.                        other comm ports.  Also, COM2 cannot be speci-
  260.